home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 February: Technology Seed / Mac Tech Seed Feb '97.toast / OpenDoc 1.2b2c1 / Implementation / Storage / Bento / CM / CMAPITyp.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-02-13  |  10.3 KB  |  216 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        CMAPITyp.h
  3.  
  4.     Contains:    Container Manager API Types and Constants
  5.  
  6.     Written by:    Ira L. Ruben
  7.  
  8.     Owned by:    Ed Lai
  9.  
  10.     Copyright:    © 1991 - 1996 by Apple Computer, Inc., all rights reserved.
  11.  
  12.     Change History (most recent first):
  13.  
  14.          <2>     1/15/96    TJ        Cleaned Up
  15.          <2>     8/26/94    EL        #1182308 Add kCMLittleEndianTwin flag.
  16.                                     #1182275 Add kCMMerging to open mode
  17.          <4>     1/19/94    EL        Add kCMNextGeneration for automatic
  18.                                                     generation of generation number.
  19.  
  20.     To Do:
  21. */
  22.  
  23. /* (use tabs = 2 to view this file correctly) */
  24. /*---------------------------------------------------------------------------*
  25.  |                                                                           |
  26.  |                           <<< CM_API_Types.h >>>                          |
  27.  |                                                                           |
  28.  |                  Container Manager API Types and Constants                |
  29.  |                                                                           |
  30.  |                               Ira L. Ruben                                |
  31.  |                                 11/18/91                                  |
  32.  |                                                                           |
  33.  |                  Copyright Apple Computer, Inc. 1991-1994                 |
  34.  |                           All rights reserved.                            |
  35.  |                                                                           |
  36.  *---------------------------------------------------------------------------*
  37.  
  38.  This file contains all the type and constant definitions used by the Container Manager
  39.  API.
  40.  
  41.  
  42.                                               *------------------------------*
  43.                                                 | NOTE TO DOS (80x86) USERS... |
  44.                                                 *------------------------------*
  45.  
  46.  The Container Manager should be compiled with the "large" memory model so that all
  47.  routines, pointers, etc. are "far".  All external API interfaces are appropriately
  48.  qualified this way.  Since handlers are implementation or user dependent, these files
  49.  must be compiled with the large memory model.  The only exception is local static
  50.  routines which usually can be qualified with "near" (except, of course, for handlers).
  51.  
  52.  This file uses the function and pointer memory model attribute macros defined
  53.  CM_API_Environment.h.  See that file for further details.
  54. */
  55.  
  56. #ifndef __CM_API_TYPES__
  57. #define __CM_API_TYPES__
  58.  
  59. #ifndef __CM_API_ENV__
  60. #include "CMAPIEnv.h"
  61. #endif
  62.  
  63.  
  64. /*--------------------------*
  65.  | Low level basic types... |
  66.  *--------------------------*/
  67.  
  68. typedef char                         CM_CHAR;                                    /* 1-byte objects                                            */
  69. typedef unsigned char     CM_UCHAR;
  70.  
  71. typedef short                        CM_SHORT;                                    /* 2-byte objects                                            */
  72. typedef unsigned short    CM_USHORT;
  73.  
  74. typedef long                        CM_LONG;                                    /* 4-byte objects                                            */
  75. typedef unsigned long        CM_ULONG;
  76.  
  77.  
  78. /*----------*
  79.  | Types... |
  80.  *----------*
  81.  
  82.  All Container Manager types are defined here with the intent to aid in enforcing compiler
  83.  type checking.  Note that "refNums" for session data, container control blocks, values,
  84.  and objects are uniquely typed to strictly enforce type checking of those entities. These
  85.  types are defined as pointers derived from an "incomplete type", i.e. structs.  The
  86.  structs are NOT defined.  In ANSI C, an "incomplete type" need not be defined.
  87.  
  88.  Further, for all the following types defined as pointers, a corresponding "CMconst_..." is
  89.  defined.  These allow for function paramters of the form "pointer to constant CM type".
  90.  Note that, in ANSI, "const CMFooPtr p" is NOT the same as "const CMFoo *p". The latter is
  91.  what we desire, but the former defines a "consting pointer to a CMFoo" not a "pointer to a
  92.  constant CMFoo".  Hence the additional types are required. */
  93.  
  94. typedef    struct CMSession_     CM_PTR *CMSession;        /* pointer to session (task) data            */
  95. typedef struct CMContainer_ CM_PTR *CMContainer;    /* "refNum" for containers                        */
  96.  
  97. typedef struct CMObject_         CM_PTR *CMObject;            /* "refNum" for objects                                */
  98. typedef CMObject                                         CMProperty;        /* "refNum" for property objects            */
  99. typedef CMObject                                         CMType;                /* "refNum" for type objects                    */
  100.  
  101. typedef struct CMValue_         CM_PTR *CMValue;            /* "refNum" for values                                */
  102.  
  103. typedef CM_CHAR        CM_PTR *CMOpenMode;                            /* handler open mode string pointers    */
  104. typedef CM_CHAR     CM_PTR *CMGlobalName;                        /* global unique name pointers                */
  105. typedef CM_CHAR        CM_PTR *CMErrorString;                    /* error message string pointers            */
  106. typedef CM_CHAR        CM_PTR *CMMetaData;                            /* type metadata string pointers            */
  107.  
  108. typedef void            CM_PTR *CMRefCon;                                /* reference constants ("refCon"s)        */
  109. typedef void             CM_PTR *CMPtr;                                    /* arbitrary data pointers                        */
  110.  
  111. typedef CM_UCHAR    CM_PTR *CMMagicBytes;                        /* magic byte pointers                                */
  112. typedef CM_UCHAR    CM_PTR *CMDataPacket;                        /* "new value" handler data packets        */
  113. typedef CM_UCHAR    CM_PTR *CMDataBuffer;                        /* ptr to data buffer for handlers        */
  114. typedef CM_UCHAR    CM_PTR *CMPrivateData;                    /* ptr to private CM data for handlers*/
  115.  
  116. typedef    const struct CMSession_     CM_PTR *CMconst_CMSession;        /* ptr to const types...*/
  117. typedef const struct CMContainer_ CM_PTR *CMconst_CMContainer;
  118. typedef const struct CMObject_         CM_PTR *CMconst_CMObject;
  119. typedef CMconst_CMObject                                     CMconst_CMProperty;
  120. typedef CMconst_CMObject                                     CMconst_CMType;
  121. typedef const struct CMValue_         CM_PTR *CMconst_CMValue;
  122. typedef const CM_CHAR                            CM_PTR *CMconst_CMOpenMode;
  123. typedef const CM_CHAR                         CM_PTR *CMconst_CMGlobalName;
  124. typedef const CM_CHAR                            CM_PTR *CMconst_CMErrorString;
  125. typedef const CM_CHAR                            CM_PTR *CMconst_CMMetaData;
  126. typedef const void                                CM_PTR *CMconst_CMconst_CMRefCon;
  127. typedef const void                                 CM_PTR *CMconst_CMPtr;
  128. typedef const CM_UCHAR                        CM_PTR *CMconst_CMMagicBytes;
  129. typedef const CM_UCHAR                        CM_PTR *CMconst_CMDataPacket;
  130. typedef const CM_UCHAR                        CM_PTR *CMconst_CMDataBuffer;
  131. typedef const CM_UCHAR                        CM_PTR *CMconst_CMPrivateData;
  132.  
  133. typedef CM_UCHAR    CMReference[4];                                    /* referenced object data pointers        */
  134.  
  135. typedef CM_UCHAR     CMSeekMode;                                            /* container "fseek()" handler modes    */
  136. typedef CM_UCHAR     CMBoolean;                                            /* boolean values/functs. (0==>false)    */
  137.  
  138. typedef CM_USHORT CMContainerUseMode;                            /* container open use mode flags            */
  139. typedef CM_USHORT CMContainerFlags;                                /* container label flags                            */
  140. typedef CM_USHORT    CMContainerModeFlags;                        /* container open mode flags                    */
  141. typedef CM_USHORT CMValueFlags;                                        /* value flags                                                */
  142. typedef CM_USHORT CMEofStatus;                                        /* "feof()" handler result status            */
  143.  
  144. typedef CM_LONG     CMErrorNbr;                                            /* error handler error numbers                */
  145.  
  146. typedef CM_ULONG     CMGeneration;                                        /* container generation numbers                */
  147. typedef CM_ULONG     CMSize;                                                    /* sizes                                                            */
  148. typedef CM_ULONG     CMCount;                                                /* amounts or counts                                    */
  149. typedef CM_ULONG     CMObjectID;                                            /* object ID's                                                */
  150.  
  151. CM_CFUNCTIONS                                                                            /* see CM_API_Environment.h about this*/
  152. typedef void (CM_FIXEDARGS *CMHandlerAddr)();            /* handler address pointers                      */
  153. typedef    CMHandlerAddr (CM_FIXEDARGS *CMMetaHandler)(CMType,                            /* metahandlers    */
  154.                                                                                                         CMconst_CMGlobalName);
  155. CM_END_CFUNCTIONS
  156.  
  157.  
  158. /*--------------*
  159.  | Constants... |
  160.  *--------------*/
  161.  
  162. /* The following flags are passed to CMOpenNewContainer() as CMContainerFlags.  These     */
  163. /* flags are stored in the container label and define some constant attributes about the*/
  164. /* container.     The container flags may be retrieved by calling the CMGetContainerInfo() */
  165. /* API routine.                                                                                                                                                    */
  166.  
  167. #define kCMLittleEndian        0x0001U                                    /* little-endian byte ordering                */
  168. #define kCMLittleEndianTwin    0x0101U                                    /* little-endian byte ordering                */
  169.  
  170. /* The following flags are passed to CMOpen[New]Container() as CMContainerUseMode             */
  171. /* useFlags.  They modify the open in the indicated ways. Note, kCMReading, kCMWriting, */
  172. /* kCMUpdating are also returned from CMGetContainerInfo() to indicate the mode of the     */
  173. /* container, i.e., it was opened for reading, writing, or updating.                                        */
  174.  
  175. #define kCMReading                0x0001U                                    /* container was opened for reading        */
  176. #define    kCMWriting                0x0002U                                    /* container was opened for writing        */
  177. #define kCMReuseFreeSpace    0x0004U                                    /* try to reuse freed space                      */
  178. #define kCMUpdateByAppend    0x0008U                                 /* open container for update-by-append*/
  179. #define kCMUpdateTarget        0x0010U                                    /* open container for updating target */
  180. #define kCMConverting          0x0020U                                 /* open container for converting          */
  181. #define kCMMerging              0x0040U                                 /* container may be merged                      */
  182.  
  183. #define kCMUpdating                (kCMReuseFreeSpace | kCMUpdateByAppend | kCMUpdateTarget)
  184.  
  185. /* The following flags are options to the "seek" I/O handler.                                                        */
  186.  
  187. #define kCMSeekSet                 0x00                                         /* "fseek()" handler mode (pos)                */
  188. #define kCMSeekCurrent         0x01                                         /* "fseek()" handler mode (curr+pos)    */
  189. #define kCMSeekEnd                 0x02                                         /* "fseek()" handler mode (end+pos)        */
  190.  
  191. /* The following are the flags that appear in the flags field of the TOC itself.  Some     */
  192. /* are for internal use only and do not appear in TOC entries in the container.  The         */
  193. /* comments designate which are these.                                                                                                    */
  194.  
  195. #define kCMImmediate             0x0001U                                 /* immediate value flag                                */
  196. #define kCMContinued             0x0002U                                 /* continue value flag                                */
  197.  
  198. #define kCMDynValue             0x4000U                                 /* dynamic value flag (internal use)    */
  199. #define kCMGlobalName         0x8000U                                 /* global name flag        (internal use)    */
  200.  
  201. /* The Container label contains a buffer size field which is used by the Container             */
  202. /* Manager for buffered TOC I/O. This field, times 1024, yields the actual buffer size. */
  203. /* Since this field (as it is in the label) can be returned by CMGetContainerInfo(), the*/
  204. /* following constant is provided to get the actual buffer size in bytes.                                */
  205.  
  206. #define kCMBufSizeUnits        1024                                        /* bufSize*1024==actual TOC bufr size    */
  207.  
  208. /* When we do CMOpenNewContainer updating another container, we may want to have a            */
  209. /* generation number equal to target container plus 1. It may not be easy since we do        */
  210. /* not know the generation number of the target container without opening it.                        */
  211. /* Use kCMNextGeneration in the generation number would automatically do it for you            */
  212.  
  213. #define    kCMNextGeneration    0x0000U
  214.  
  215. #endif
  216.